package com.smart.community.region.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.PageResult;
import com.smart.community.region.dto.OwnerHouseholdDTO;
import com.smart.community.region.dto.OwnerHouseholdQueryDTO;
import com.smart.community.region.entity.OwnerHousehold;
import com.smart.community.region.vo.OwnerHouseholdVO;

import java.util.List;

/**
 * 业主房户关联服务接口
 * 
 * @author Wu.Liang
 * @since 2025-08-20
 * @version 1.0.0
 */
public interface IOwnerHouseholdService extends IService<OwnerHousehold> {
    
    /**
     * 根据业主ID查询关联的房户列表
     * 
     * @param ownerId 业主ID
     * @return 业主房户关联列表
     * @throws Exception 统一异常
     */
    List<OwnerHousehold> getByOwnerId(Long ownerId) throws Exception;
    
    /**
     * 根据业主ID查询关联的房户列表（VO格式）
     * 
     * @param ownerId 业主ID
     * @return 业主房户关联VO列表
     * @throws Exception 统一异常
     */
    List<OwnerHouseholdVO> getOwnerHouseholdVOs(Long ownerId) throws Exception;
    
    /**
     * 根据房户ID查询关联的业主列表
     * 
     * @param householdId 房户ID
     * @return 业主房户关联列表
     * @throws Exception 统一异常
     */
    List<OwnerHousehold> getByHouseholdId(Long householdId) throws Exception;
    
    /**
     * 根据房户ID查询关联的业主列表（VO格式）
     * 
     * @param householdId 房户ID
     * @return 业主房户关联VO列表
     * @throws Exception 统一异常
     */
    List<OwnerHouseholdVO> getHouseholdOwnerVOs(Long householdId) throws Exception;
    
    /**
     * 根据房户ID集合查询关联的业主列表
     * 
     * @param householdIds 房户ID集合
     * @return 业主房户关联列表
     * @throws Exception 统一异常
     */
    List<OwnerHousehold> getByHouseholdIds(List<Long> householdIds) throws Exception;
    
    /**
     * 根据业主ID和房户ID查询关联记录
     * 
     * @param ownerId 业主ID
     * @param householdId 房户ID
     * @return 业主房户关联记录
     * @throws Exception 统一异常
     */
    OwnerHousehold getByOwnerIdAndHouseholdId(Long ownerId, Long householdId) throws Exception;
    
    /**
     * 根据房户ID查询主业主
     * 
     * @param householdId 房户ID
     * @return 主业主关联记录
     * @throws Exception 统一异常
     */
    OwnerHousehold getPrimaryOwnerByHouseholdId(Long householdId) throws Exception;
    
    /**
     * 根据业主ID查询主业主的房户列表
     * 
     * @param ownerId 业主ID
     * @return 主业主房户关联列表
     * @throws Exception 统一异常
     */
    List<OwnerHousehold> getPrimaryHouseholdsByOwnerId(Long ownerId) throws Exception;
    
    /**
     * 创建业主房户关联
     * 
     * @param ownerId 业主ID
     * @param householdId 房户ID
     * @param isPrimaryOwner 是否主业主
     * @throws Exception 统一异常
     */
    void createOwnerHousehold(Long ownerId, Long householdId, Boolean isPrimaryOwner) throws Exception;
    
    /**
     * 创建业主房户关联（DTO方式）
     * 
     * @param dto 关联信息
     * @return 关联ID
     * @throws Exception 统一异常
     */
    Long createOwnerHousehold(OwnerHouseholdDTO dto) throws Exception;
    
    /**
     * 更新业主房户关联
     * 
     * @param id 关联ID
     * @param dto 关联信息
     * @throws Exception 统一异常
     */
    void updateOwnerHousehold(Long id, OwnerHouseholdDTO dto) throws Exception;
    
    /**
     * 删除业主房户关联
     * 
     * @param ownerId 业主ID
     * @param householdId 房户ID
     * @throws Exception 统一异常
     */
    void deleteOwnerHousehold(Long ownerId, Long householdId) throws Exception;
    
    /**
     * 删除业主房户关联（根据关联ID）
     * 
     * @param id 关联ID
     * @throws Exception 统一异常
     */
    void deleteOwnerHousehold(Long id) throws Exception;
    
    /**
     * 删除业主的所有房户关联
     * 
     * @param ownerId 业主ID
     * @throws Exception 统一异常
     */
    void deleteByOwnerId(Long ownerId) throws Exception;
    
    /**
     * 删除房户的所有业主关联
     * 
     * @param householdId 房户ID
     * @throws Exception 统一异常
     */
    void deleteByHouseholdId(Long householdId) throws Exception;
    
    /**
     * 设置主业主
     * 
     * @param ownerId 业主ID
     * @param householdId 房户ID
     * @throws Exception 统一异常
     */
    void setPrimaryOwner(Long ownerId, Long householdId) throws Exception;
    
    /**
     * 检查业主房户关联是否存在
     * 
     * @param ownerId 业主ID
     * @param householdId 房户ID
     * @return 是否存在
     * @throws Exception 统一异常
     */
    boolean existsByOwnerIdAndHouseholdId(Long ownerId, Long householdId) throws Exception;
    
    /**
     * 分页查询业主房户关联列表
     * 
     * @param queryDTO 分页查询条件
     * @return 分页结果
     * @throws Exception 统一异常
     */
    PageResult<OwnerHouseholdVO> getOwnerHouseholdPage(OwnerHouseholdQueryDTO queryDTO) throws Exception;
    
    /**
     * 根据ID获取业主房户关联详情
     * 
     * @param id 关联ID
     * @return 关联详情
     * @throws Exception 统一异常
     */
    OwnerHouseholdVO getOwnerHouseholdVOById(Long id) throws Exception;
}
